API 文档方案：OpenAI 规范与 AI 快速生成
你会学到什么
前面四节讲了 Mermaid 图表、draw.io 可视化、专业图表选型、Word 文档格式保留——这些都在解决"文档里怎么画图、怎么排版"的问题。
本节换一个角度：API 文档。RESTful API、GraphQL、组件库的 Props/Events/Slots，这些都属于"接口文档"。接口文档的核心痛点是：代码一改，文档就过期。
本节讲清楚：
- API 文档为什么不能手动写
- OpenAPI 3.x 规范和主流渲染工具（Swagger UI / Redoc / Scalar）
- 用 Claude Code 从 TypeScript 类型自动生成 OpenAPI spec
- 用 AI 一键生成可部署的文档站点
- 给 Vue 3 组件库生成 Props/Events/Slots 文档的实战案例
- 从纯 API 站升级到 VitePress 文档站，以及"代码改了文档自动跟着改"的两条路（skill / hook）
为什么 API 文档不能手动写
手动维护的三大死穴
| 痛点 | 表现 | 后果 |
|---|---|---|
| 代码改了文档没改 | 接口参数变了、文档还是旧版 | 前端调用报错，联调时才发现 |
| 示例代码过时 | 返回值结构改了、示例还用旧的 | 第三方对接失败，反复沟通 |
| 格式不统一 | 有人用 JSON、有人用表格、有人纯文字 | 阅读体验差，信息查找困难 |
API 文档的三个场景
| 场景 | 谁用 | 需要什么 |
|---|---|---|
| 前后端协作 | 前端开发者 | 请求参数、响应结构、错误码、在线调试 |
| 第三方对接 | 合作方/客户 | 完整的接口列表、认证方式、示例代码 |
| 自动化测试 | 测试工程师 | 结构化的接口描述，能生成测试用例 |
这三种场景对文档的要求不同，但核心是一致的：文档必须是机器可读的结构化数据，而不是人写的 Word/PDF。
OpenAPI 3.x 规范：API 文档的"源代码"
什么是 OpenAPI 规范
OpenAPI 规范（原名 Swagger 规范）是一份 YAML 或 JSON 文件，描述 RESTful API 的所有信息：端点、参数、响应、认证、示例。它就像是 API 的"类型定义"。
openapi: 3.0.3
info:
title: 用户服务 API
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: 获取用户列表
parameters:
- name: page
in: query
schema:
type: integer
default: 1
responses:
'200':
description: 成功
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
yaml
这个 YAML 文件就是 API 文档的"源代码"。你可以：
- 用 Swagger UI 渲染成可交互的网页
- 用 Redoc 渲染成静态文档
- 用工具生成客户端 SDK（TypeScript/Java/Python）
- 用工具生成服务器存根代码
主流文档工具对比
| 工具 | 类型 | 样式风格 | 在线调试 | AI 支持度 | 免费/付费 |
|---|---|---|---|---|---|
| Swagger UI | 渲染器 | 三栏布局（导航+参数+响应） | ✅ 内置 Try it out | ⭐⭐⭐⭐⭐ | 免费 |
| Redoc | 渲染器 | 左侧导航+右侧内容，简洁 | ❌ 无调试功能 | ⭐⭐⭐⭐ | 免费 |
| Scalar | 渲染器 | 现代、美观、可交互 | ✅ 内置 HTTP 客户端 | ⭐⭐⭐⭐ | 免费+付费 |
| Stoplight Elements | 渲染器 | 卡片式、高度可定制 | ✅ | ⭐⭐⭐ | 免费+付费 |
| Docusaurus Plugin | 静态站点 | 文档站风格 | ❌ | ⭐⭐⭐ | 免费 |
选择建议
选择流程
│
├── 需要在线调试 → Swagger UI / Scalar
├── 只读文档、追求美观 → Redoc
├── 需要嵌入现有文档站 → Docusaurus Plugin
└── 需要高度定制 → Stoplight Elements
text
大多数场景：Scalar（美观+可调试+免费），或者 Redoc（静态部署简单）。
用 Claude Code 生成 OpenAPI 规范文件
方式一：从接口描述直接生成
给 Claude Code 一段接口描述，让它输出 OpenAPI YAML：
请生成 OpenAPI 3.x 规范文件，包含以下接口：
1. POST /auth/login - 用户登录
- 请求体：username（字符串）、password（字符串）
- 响应：token（字符串）、expiresIn（整数，秒）
- 错误：401 用户名或密码错误
2. GET /users/me - 获取当前用户信息
- 需要 Bearer Token 认证
- 响应：id、username、email、createdAt
markdown
Claude Code 会输出完整的 YAML 文件。你可以让它：
把上面的 OpenAPI 规范保存为 openapi.yaml
markdown
方式二：从 TypeScript 类型生成
如果你有 TypeScript 的类型定义，可以让 Claude Code 自动转成 OpenAPI：
// types/user.ts
export interface LoginRequest {
username: string;
password: string;
}
export interface LoginResponse {
token: string;
expiresIn: number;
}
export interface User {
id: number;
username: string;
email: string;
createdAt: string; // ISO 8601
}
typescript
请把 types/user.ts 中的类型转换为 OpenAPI 3.x schemas
markdown
Claude Code 会输出：
components:
schemas:
LoginRequest:
type: object
required:
- username
- password
properties:
username:
type: string
password:
type: string
LoginResponse:
type: object
properties:
token:
type: string
expiresIn:
type: integer
yaml
方式三：用自动化工具从代码生成
手动让 AI 转换适合一次性需求，长期维护建议用自动化工具：
| 工具 | 语言 | 输入 | 输出 |
|---|---|---|---|
| tsoa | TypeScript/Node.js | 装饰器标注的 Controller | OpenAPI + 路由代码 |
| nestjs/swagger | NestJS | 装饰器 | OpenAPI |
| fastify-swagger | Fastify | Schema 定义 | OpenAPI |
| springdoc-openapi | Java Spring | 注解 | OpenAPI |
tsoa 实战示例：
// src/controllers/UserController.ts
import { Route, Post, Body, Response } from 'tsoa';
interface LoginRequest {
username: string;
password: string;
}
interface LoginResponse {
token: string;
expiresIn: number;
}
@Route('auth')
export class UserController {
@Post('login')
@Response<401>('Unauthorized')
public async login(
@Body() body: LoginRequest
): Promise<LoginResponse> {
// 实现代码
return { token: 'xxx', expiresIn: 3600 };
}
}
typescript
运行 tsoa spec，自动生成 openapi.json。
用 AI 快速生成文档站点
Redoc：最简单的静态站点
Redoc 是一个单文件 HTML，不需要后端，直接在浏览器里渲染 OpenAPI 文件。
生成方式一：CDN 直接引用
创建 index.html：
<!DOCTYPE html>
<html>
<head>
<title>API 文档</title>
<link
href="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.css"
rel="stylesheet"
>
</head>
<body>
<redoc spec-url="openapi.yaml"></redoc>
<script
src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"
></script>
</body>
</html>
html
把 openapi.yaml 和 index.html 放到同一个目录，用 npx serve 启动静态服务器，访问 http://localhost:3000 就能看到文档。
生成方式二：用 CLI 构建
npm install -g @redocly/cli
redocly build-docs openapi.yaml --output api.html
bash
生成一个单文件 api.html，可以部署到任何静态托管（GitHub Pages、Vercel、Nginx）。
Swagger UI：带调试功能的文档
Swagger UI 自带 "Try it out" 按钮，可以直接在文档页面发请求。
npm install swagger-ui-dist
bash
创建 index.html：
<!DOCTYPE html>
<html>
<head>
<link
rel="stylesheet"
href="node_modules/swagger-ui-dist/swagger-ui.css"
>
</head>
<body>
<div id="swagger-ui"></div>
<script src="node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
SwaggerUIBundle({
url: 'openapi.yaml',
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
});
</script>
</body>
</html>
html
Scalar：现代化的选择
Scalar 是近两年崛起的主流方案，样式更现代，内置 HTTP 客户端。
npm install @scalar/api-reference
bash
<!DOCTYPE html>
<html>
<head>
<title>API 文档</title>
</head>
<body>
<script
id="api-reference"
data-url="openapi.yaml"
></script>
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
</body>
</html>
html
三者对比
| 特性 | Redoc | Swagger UI | Scalar |
|---|---|---|---|
| 样式年代感 | 较旧 | 经典但老 | 现代 |
| Try it out | 无 | 有 | 有（更强大） |
| 单文件部署 | ✅ | ✅ | ✅ |
| 中文支持 | ✅ | ✅ | ✅ |
| 学习成本 | 最低 | 低 | 低 |
默认推荐：内部团队用 Scalar（美观+调试），对外公开用 Redoc（简洁、加载快）。
三者的差异用官网 Live Demo 各点五分钟就能感受出来：Swagger UI 的强项是 Try it out——点开接口、填参数、Execute，直接向 spec 里配置的服务端点发请求并把响应渲染在页面上，联调时极方便，但界面观感是上一个时代的；Redoc 的三栏排版和参数表格最清晰（每个参数的类型、描述、响应码 200/404/500 一目了然），代价是没有调试按钮；Scalar 界面最现代、内置 HTTP 客户端可直接发请求，同时提供商业化托管服务。本节后续以最成熟稳定的 Swagger UI 与 Redoc 为主线。
五分钟实战：给现有项目装上 API 文档
大模型出现之前，"从接口生成 API 文档"就有一批成熟方案（Swagger/Swagger UI/Redoc），因为 API 文档变化频率太高，从来不该手写。AI 时代这件事变得更极端——一句话完成集成。拿一个只有路由没有文档的 Node.js 项目（课程资料的 api-docs 示例）为例，用 Claude Code 打开项目目录后直接说：
集成 Swagger（OpenAPI）到当前项目，扫描现有路由生成接口文档，并启动让我预览。
markdown
实测整个流程不超过五分钟：AI 选型（swagger-ui-express 或 swagger-jsdoc 一类中间件）→ 扫描路由与参数 → 生成 openapi.json/yaml → 挂载 /api-docs 端点 → 启动服务。中途遇到端口占用或依赖缺失报错，直接回一句"你来启动/修复"，让它自己处理并把进程管理也交给它。
从纯 API 站到 VitePress 文档站
Swagger UI 渲染出来的站是给开发人员看的。但技术文档的受众经常不止开发：产品、后端协作方更关心"快速定位业务相关的接口在哪"，而 Swagger 的分组标签往往是 user、order 这类英文（甚至拼音）命名，非开发读者根本找不到入口。
解决思路是把 API 文档嵌入一个完整的文档站：前面介绍项目背景和业务说明，中间是结构化的接口参考，后面放扩展功能说明。前端生态里最适合的就是 VitePress（本课程文档站同款，Vite + Vue 驱动的 Markdown 静态站点生成器，当前稳定版 1.6.4，2.0 处于 alpha 阶段（2026-11-07 核实））；React 侧的对应方案是 Docusaurus。
链路分三步：
- 初始化文档站：在项目
docs/目录初始化 VitePress 结构（同样可以一句话交给 AI："在当前目录的 docs 目录中初始化 VitePress"） - OpenAPI → Markdown：把 swagger spec 转成 VitePress 的 Markdown 页面（接口总览表 + 每个接口的参数/响应详情）。每家公司对文档结构要求不同——表格型、说明型、测试大纲、测试用例都可以，描述清楚你要的结构即可
- 保持同步：API 变更后文档自动更新（见下）
实际操作中第二步 AI 经常主动完成——只要求它"根据 swagger 更新文档站的 markdown"，它会直接在 docs/ 下按业务域组织好目录和页面。
文档随代码自动更新的两条路
| 方式 | 触发机制 | 适合场景 |
|---|---|---|
| Skill（主动） | 你说"更新 API 文档"时执行 | 改动不频繁，想人工把关每次更新 |
| Hook（被动） | 检测到代码/文档变化，会话结束（Stop）时自动执行 | 改动频繁，希望无感同步 |
Skill 方案：把"从 swagger 到 VitePress markdown"的转换过程固化成一个 skill，描述清楚输入（swagger 文件路径）、输出（markdown 目录结构、页面模板）和触发词：
扩展一个 skill：当 API 发生变化的时候，自动读取最新的 swagger spec，
更新 docs/ 目录下对应的 markdown 文档与接口属性。
markdown
Hook 方案：注册一个 Stop 钩子（第3章 05 节讲过 Hooks 机制），会话结束时检查本次是否改动了 src/routes/ 或接口相关文件，是则自动重新生成受影响的 markdown 页面。两者可以并用：hook 保底防遗漏，skill 用于大重构后的人工全量刷新。
实战案例：给 Vue 3 组件库生成 API 文档
组件库的 API 文档不同于 RESTful API，但它也是"接口文档"——Props（输入）、Events（输出）、Slots（插槽）。
方案一：TypeDoc（自动从 TS 类型生成）
npm install -D typedoc
bash
配置 typedoc.json：
{
"entryPoints": ["src/components"],
"out": "docs",
"excludePrivate": true,
"categorizeByGroup": true,
"categoryOrder": ["Button", "Form", "*"],
"kindSortOrder": [
"Reference",
"Class",
"Interface",
"TypeAlias"
]
}
json
运行 typedoc，生成 HTML 文档。
方案二：VitePress + 自定义组件
更灵活的方案是用 VitePress 搭建文档站，然后用 AI 自动生成组件的 API 表格。
给 Claude Code 输入：
请从以下 Vue 3 组件代码生成 API 文档表格：
<template>
<button
:class="['btn', `btn-${type}`, `btn-${size}`, { 'btn-disabled': disabled }]"
:disabled="disabled"
@click="handleClick"
>
<slot></slot>
</button>
</template>
<script setup lang="ts">
interface Props {
type?: 'primary' | 'secondary' | 'danger';
size?: 'small' | 'medium' | 'large';
disabled?: boolean;
}
interface Emits {
(e: 'click', event: MouseEvent): void;
}
const props = withDefaults(defineProps<Props>(), {
type: 'primary',
size: 'medium',
disabled: false,
});
const emit = defineEmits<Emits>();
const handleClick = (e: MouseEvent) => {
if (!props.disabled) {
emit('click', e);
}
};
</script>
markdown
Claude Code 输出 Markdown 表格：
## Props
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| type | `'primary' \| 'secondary' \| 'danger'` | `'primary'` | 按钮类型 |
| size | `'small' \| 'medium' \| 'large'` | `'medium'` | 按钮尺寸 |
| disabled | `boolean` | `false` | 是否禁用 |
## Events
| 事件名 | 参数类型 | 说明 |
|-------|---------|------|
| click | `MouseEvent` | 点击按钮时触发（禁用状态不触发） |
## Slots
| 插槽名 | 说明 |
|-------|------|
| default | 按钮内容 |
markdown
把这段 Markdown 放到 VitePress 文档里，就是一份完整的 API 文档。
方案三：用 Storybook + 自动生成
Storybook 是组件库文档的标准方案，它支持自动提取 Props：
npx storybook@latest init
bash
创建 src/components/Button.stories.ts：
import type { Meta, StoryObj } from '@storybook/vue3';
import Button from './Button.vue';
const meta: Meta<typeof Button> = {
title: 'Components/Button',
component: Button,
tags: ['autodocs'],
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: {
type: 'primary',
},
};
typescript
Storybook 会自动从 Vue 组件提取 Props，生成 API 文档页面。
总结
| 需求 | 推荐方案 | 理由 |
|---|---|---|
| RESTful API 文档 | OpenAPI + Scalar/Redoc | 标准化、工具链成熟 |
| 需要在线调试 | Swagger UI / Scalar | 内置 HTTP 客户端 |
| 静态文档站 | Redoc | 单文件部署、加载快 |
| 面向产品/协作方的完整文档站 | VitePress + OpenAPI 转 Markdown | 业务可读，skill/hook 保持同步 |
| 从代码自动生成 | tsoa / springdoc | 代码改动自动同步 |
| Vue 组件库 | Storybook + autodocs | 自动提取 Props/Events/Slots |
| 用 AI 一次性生成 | Claude Code 输出 YAML/Markdown | 快速、灵活 |
一句话原则
API 文档的核心是结构化描述（OpenAPI spec/TS 类型），渲染器只是外观。用 Claude Code 生成 spec 文件，用 Redoc/Scalar 渲染，这是性价比最高的组合；受众不止开发时，再套一层 VitePress 文档站。
下一步
- 下一节讲 06-超长文档生成策略：30 页以上的文档怎么用 ralph-loop 分段生成
- 文档要交付 Word 时，看 04-如何固定docx的输出风格：交叉引用、题注与格式保留
↑